home *** CD-ROM | disk | FTP | other *** search
/ Software Explosion / Software Explosion (Fore-Matt Home Computing)(1996).iso / system / c / play16.doc < prev    next >
Text File  |  1996-09-08  |  12KB  |  292 lines
  1.  
  2. -- Play16 version 1.2 - a versatile soundplayer for the Amiga --
  3.  
  4.  
  5. Features in brief
  6. -----------------
  7.  - autodetects and plays several soundfiles, up to 16 bit / 56 kHz / stereo
  8.  - always correct playback speed, even for sounds >28 kHz
  9.  - plays mono sounds on *both* channels, not only on the left one
  10.  - plays files that are larger than memory
  11.  - preloading for exactly timed start of playback
  12.  - fast uLaw decompression
  13.  - system friendly audio channel allocation
  14.  - supported Filetypes are:
  15.  
  16.    * Microsoft RIFF-WAVE  (.WAV)  mono / stereo, 8 / 16 bit, linear / uLaw
  17.    * Sun/NeXT Audio       (.AU)   mono / stereo, 8 / 16 bit, linear / uLaw
  18.    * MacroSystem MAUD     (.MAUD) mono / stereo, 8 / 16 bit, linear
  19.    * Apple/SGI/Amiga AIFF (.AIFF) mono / stereo, 8 / 16 bit, linear
  20.    * Amiga IFF-8SVX       (.IFF)  mono / stereo, 8      bit, linear
  21.    * Any raw sound data as long as it matches one of the following:
  22.      -  8 bit signed
  23.      -  8 bit unsigned
  24.      - 16 bit signed, Intel format    (LSB first)
  25.      - 16 bit signed, Motorola format (MSB first)
  26.  
  27.  
  28. What do I need to use Play16?
  29. -----------------------------
  30. Any Amiga running Kickstart/Workbench 2.04 or greater.
  31.  
  32.  
  33. What does it do?
  34. ----------------
  35. Basically, Play16 is capable of playing uncompressed and _some_ compressed
  36. soundfiles through Amiga's standard audio device. If the actual resolution
  37. or playback rate exceeds that of the Amiga hardware, realtime conversion
  38. is done so that the sound is being played back correctly.
  39.  
  40. You can even play 16 bit / 44.1 kHz sounds, providing all parts of
  41. your system can keep up with the high data transfer rate and lots
  42. of calculations needed for this task. (In this case an accelerated
  43. Amiga is recommended :-)
  44.  
  45. I don't want Play16 to be a program that plays each and every exotic format
  46. that exists somewhere. However, I intend to support as many popular file
  47. types as possible
  48.  
  49.  
  50. How do I use it?
  51. ----------------
  52. Simply type "Play16 <filename>" and that's it!
  53. All possible options will be explained later. If you set none of them, the
  54. defaults will be used.
  55.  
  56.  
  57. Why Play16?
  58. -----------
  59. 16 bit soundcards are becoming more and more popular, especially on the
  60. PC. The common file format over there is Microsoft's (yuck! :)) RIFF-
  61. WAVE format.
  62. I didn't find any CLI based program to play back 16 bit recordings, on a
  63. standard Amiga, so I decided to write one myself.
  64.  
  65.  
  66. Why CLI based and no GUI?
  67. -------------------------
  68. There are so many GUI based directory utilities, simply use Play16 as an
  69. external player. Consult the manual of your software package on how to
  70. do it. Application example: Assign "Play16 <filename> PRELOAD" to a button
  71. called "Jingle". Select the desired soundfile and press the Jingle-button.
  72. Wait for the appropriate moment and hit the return key - here comes the
  73. sound! Nice when audio dubbing your home videos or even on parties :-)
  74.  
  75.  
  76. How does it work? (technical info)
  77. ----------------------------------
  78. The standard Amiga audio device is limited to 8 bit / 28 kHz playbck
  79. when using DMA. With the introduction of ECS the 28 kHz DMA barrier
  80. was broken - but only if the current displaymode was one with double
  81. scan rate like productivity. If you don't have ECS or if you simply
  82. don't want to switch to Productivity just to listen to your desired
  83. sound, Play16 can can halve the sample rate during playback. In the
  84. current version of Play16 only 8 bit output is supported so 16 bit
  85. sounds are converted accordingly.
  86. To play back even long sounds, the popular method of double buffering
  87. is used. Alternatively, all data can be loaded into memory before
  88. playback. This is useful when playing short sounds or when loading
  89. the sound from disk.
  90.  
  91.  
  92. What options are provided?
  93. --------------------------
  94. If you are not familiar with the AmigaOS 2.x commandline template, see
  95. the examples below and consult the AmigaOS manual for furhter information.
  96.  
  97. FAST/S      Do not automatically switch to halve sample rate if the
  98.             soundfile's rate exceeds 28 kHz. Use this option when
  99.             running your Amiga in Productivity or similar display
  100.             modes.
  101.  
  102. SINGLE/S    Use only one buffer rather then two and load all data into
  103.             memory befor playback.
  104.  
  105. BUFFER/N    Buffersize in samples. May vary from 32768 to 131072. The
  106.             amount of allocated memory also depends on whether the sound
  107.             is mono or stereo, 8 bit or 16 bit.
  108.             Default is 65536 samples, values are rounded to multiples of
  109.             32768.
  110.             Note that it is useless to modify this value when in single
  111.             buffer mode :)
  112.  
  113. VERBOSITY/N Sets the level of verbosity.
  114.             0: Just display the banner and error messages
  115.             1: Print additional information about the sound file,
  116.                allocated memory, etc.
  117.             2: Progress information
  118.             3: Debugging information (may look a bit weird :)
  119.             Default is level 0.
  120.  
  121. LOOPS/N     Determines the number of loops to be played.
  122.             Default is 1 loop. (Play the sound once.)
  123.             This option is not yet supported in SINGLE mode.
  124.  
  125. PRELOAD/S   Load enough data into memory for immediate start of playback
  126.             a a keypress
  127.  
  128. RAW/S       Disable autodetect and tell Play16 what the actual format of
  129.             the sound data is.
  130.  
  131. The following options are only valid when in RAW mode:
  132.  
  133. FREQ/N      Sampling frequency in Hz
  134. TRACKS/N    Number of tracks, 1 for mono, 2 for stereo
  135. BITS/N      Resolution in bits, may be 8 or 16
  136. HEADER/N    Length of header: This is the number of bytes to be skipped
  137.                               at the beginning of the file.
  138. UNSIGNED/S  Data is unsigned, not signed (only valid for  8 bit sounds)
  139. INTEL/S     Data is in Intel format      (only valid for 16 bit sounds)
  140. ULAW/S      Data is compressed using the uLaw compression scheme
  141.  
  142. The default settings are: 22050 Hz, mono, 8 bits, no header.
  143.  
  144. Examples:
  145.  
  146. a) Play16 music.wav
  147.     Simply play the file called music.wav once and directly from harddisk.
  148.  
  149. b) Play16 music.wav SINGLE
  150.     Same as above but load all data into memory before playback. Use this
  151.     when loading soundfiles from floppy disk.
  152.  
  153. c) Play16 music.wav SINGLE VERBOSITY=1
  154.     Same as b, but with additional information being printed out.
  155.  
  156. d) Play16 rhythm.wav LOOPS=10
  157.         Play the rhythm as a continuous loop, i.e. over and over again (10 times)
  158.  
  159. e) Play16 explosion.wav SINGLE PRELOAD
  160.     Load the complete explosion sound into memory, then wait for you to hit
  161.     <return> before playback.
  162.  
  163.  
  164. How do I use this RAW mode?
  165. ---------------------------
  166. Umm, err, difficult to explain, even harder to understand...
  167. Well, if you know the data format of the soundfile, simply set RAW, FREQ,
  168. TRACKS, BITS, UNSIGNED and INTEL accordingly. If you don't, the only
  169. way to find it out is by trial and error :) Here are some tips to make
  170. it a bit easier:
  171.  
  172. Don't set HEADER to an odd number. (Leave it at 0, first.)
  173. If you set BITS to 16 and hear nothing but noise, try to set INTEL.
  174. If you set BITS to 8 and the sound is distorted, try to set UNSIGNED.
  175. If the above does not help, try different combinations of BITS, INTEL
  176. and UNSIGNED.
  177.  
  178. If you manage to get a recognisable sound output which is either too
  179. fast or too slow, start experimenting on TRACKS and FREQ.
  180.  
  181.  
  182. Legal stuff
  183. -----------
  184. Play16 is copyrighted freeware. It may be distributed freely as long as
  185. no modifications are made to the executable and this document. A nominal
  186. fee may be asked to cover distribution costs.
  187.  
  188. Play16 may not be used for any commercial purposes or included with any
  189. commercial product without the written permission of the author.
  190.  
  191. No responsibilities are taken for damaged speakers, amplifiers, Amigas
  192. or any other components or data involved while using Play16.
  193.  
  194. Although I've done some beta testing I can't guarantee that Play16 will
  195. not crash! If you find any bugs, let me know.
  196.  
  197.  
  198. Miscellaneous
  199. -------------
  200. I don't claim Play16 to be fast. I've done some optimizing - but because
  201. the loader/converter module is a universial one, more data is actually
  202. being moved around different memory blocks than needed for playback.
  203. This method will however provide the basis for future enhancements in the
  204. playback routine like cascading two channels to archieve 14 bit output.
  205. I may also support some soundcards as well.
  206.  
  207. * Please note that English is not my native language :)
  208.  
  209. I can be reached at...
  210.  
  211. Internet: wenzel@unixserv.rz.fh-hannover.de
  212.           Thomas_Wenzel@aventure.fido.de
  213. Fido:     2:243/6050.28 or 2:241/1035.6
  214.           Mail routing _is_sometimes_ unreliable in FidoNet :-(
  215. Snail:    Thomas Wenzel
  216.           Dresdener Str. 20
  217.           31789 Hameln
  218.           Germany
  219.  
  220. If you use this program, please send me a mail. I'd like to know how many
  221. people are interested in it at all.
  222.  
  223.  
  224. History
  225. -------
  226. V0.5▀   - Initial beta test release
  227.  
  228. V0.6▀   - Optimized the code a bit.
  229.  
  230. V0.7▀   - Fixed some severe bugs that caused Play16 to crash when trying
  231.           to load corrupted files.
  232.  
  233. V0.8▀   - Play16 can now be stopped by pressing ctrl-c during playback. The
  234.           buffer that is currently being played will be finished first.
  235.         - Automatic filter control depending on sample rate.
  236.  
  237. V0.9▀   - Added 'loop'-option. Sample can be played several times.
  238.         - All time consuming routines now in hand optimized assembler code.
  239.  
  240. V1.0▀   - Play16 now uses standard OS2.x commandline template.
  241.           Thanks to Kai for persuading me to do this :)
  242.  
  243. V1.0    - Done some minor bugfixes.
  244.  
  245. V1.1    - Oops! Play16 caused some Enforcer hits. Fixed that.
  246.           Thanks to Rod Schnell for reporting it.
  247.         - Added 'single'-option. Sound can be loaded completely into memory
  248.           before playing. No looping possible in this case yet!
  249.         - Playback time in minutes:seconds displayed if verbose >= 1
  250.         - uLaw decompression for WAVE-Files, using a decoding table
  251.           for maximum speed (didn't do much testing on it, hope it works!)
  252.         - MAUD filetype support (why do there have to be so many formats?)
  253.         - AIFF filetype support
  254.           Note that the AIFF sounds saved with MacroSystem's MPro software
  255.           contain a corrupt ANNO chunk :-/
  256.           Play16 will detect this and play the file anyway.
  257.         - ctrl-c now stops playback immediately.
  258.           Thanks to Marc for some programming tips about that.
  259.  
  260. V1.2    - IFF-8SVX filetype support (only uncompressed files!)
  261.         - RAW data support: _Any_ data can be played
  262.         - Preload feature added
  263.         - Fixed a bug that caused illegal memory access (hopefully)
  264.           Thanks to Ignatios Souvatzis for reporting it.
  265.         - Improved chunk handling
  266.  
  267.  
  268. Future plans
  269. ------------
  270. - other uLaw-formats and maybe Creative-VOC support
  271. - ADPCM decompression (still having difficulties coding the algorhytm)
  272.   (Could anyone please send me the 16bit VOC specs, including ADPCM?)
  273. - some of the file types saved by Macintosh software (e.g. Sound-Designer)
  274. - 14 bit output (this &%$!# routine still won't work :-((( )
  275. - Soundcard support
  276. - More information about Sound (AUTHOR or ANNO-Chunk)
  277.   (coming very soon, made possible by the new chunk handling routines)
  278.  
  279.  
  280. Credits
  281. -------
  282. Thanks go to the following persons:
  283.  
  284. Kai Stuke   for many vital hints on C programming and the Amiga
  285.             audio device.
  286.             for beta testing this program.
  287.  
  288. Marc Fⁿhrer for doing some beta testing as well.
  289.             for some hints on optimizing the code.
  290.  
  291. Clete Baker for supplying the AIFF- and SDII specs.
  292.